<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
	<meta http-equiv="content-type" content="text/html;charset=utf-8" />
	<title>Allegro Stuff</title>
	<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<!-- menu -->
	<div id="navmain">
	<ul>
		<li><a href="index.html">Overview</a></li>
		<li><a href="install.html">Installation</a></li>
		<li><a href="config.html">Configurator</a></li>
		<li><a href="animation.html">Animation</a></li>
		<li><a href="framework.html">Framework</a></li>
		<li><a href="tranzam.html">Tutorial</a></li>
	</ul>
	</div>
	<div id="navsub">
	<ul>
		<li><a href="#xml">XML File</a></li>
		<li><a href="#elements">Elements/Attributes</a></li>
		<li><a href="#methods">Methods</a></li>
		<li><a href="#optimum">Optimising</a></li>
		<li><a href="#playback">Usage</a></li>
		<li><a href="#tutorial">Examples</a></li>
		<li><a href="#manlibrary">Manual Library</a></li>
	</ul><span class="smallprint">This menu will stay fixed with a proper browser.</span>
	<p>
	 <a href="http://jigsaw.w3.org/css-validator/">
	  <img style="border:0;width:88px;height:31px"
		   src="http://jigsaw.w3.org/css-validator/images/vcss" 
		   alt="Valid CSS!" />
	 </a>
	</p>
	<p>
      <a href="http://validator.w3.org/check?uri=referer"><img
          src="http://www.w3.org/Icons/valid-xhtml10"
          alt="Valid XHTML 1.0!" height="31" width="88" /></a>
    </p>
<p><a href="http://www.bloggerheads.com/bbc/" ><img src="http://www.bloggerheads.com/bbc/bbc.gif" width="90" height="45"  alt="Click here to find out why." /></a></p>
<p><a href="http://retrospec.sgn.net" ><img src="retrospec.gif" width="150" alt="Fine games" /></a></p>
	</div>
<!-- menu -->

	<div id="main">
		<a name="library"></a>
		<h1>Animation Library</h1>
<a name="xml"></a>
<h2>XML File</h2>
<p>The Animation library serves two purposes, firstly it is a repository for graphics and animations (allowing sheet/tiled graphics, support for memory, system and video bitmaps) and secondly an animation playback library to perform various actions on your bitmaps (such as animate to a set time/framerate, fade, use countdown timers, etc). The animations and graphics are fully described in the XML (file or string). The code in the examples (main.cpp file) simply 
applies different actions to the animations and graphics. The sample XML files contain full
documentation for the XML file elements and attributes and are described below as well.</p>
<p>This is the core of an animation file:</p>
<p class="code">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;animations&gt;
	&lt;global 
	/&gt;
	&lt;graphic
	/&gt; 
	&lt;animation /&gt;
	&lt;animation&gt;
		&lt;animationitem /&gt;
		&lt;animationitem /&gt;
	&lt;/animation&gt;
&lt;/animations&gt;
</p>
<p>There is one 'animations' block that contains zero or one global section and a number of graphic/animation elements. 
Each 'graphic' describes one bitmap only. It can be simply a static graphic you wish to use in 
your game or if you are using sheet/tiled graphics it can be a sheet/tiled master file, or
it can even be a child element within a sheet/tiled master file. <br/><br />
Each 'animation' element describes a series of bitmaps that you use as an animation. Each item is contained within a 'animationitem'
element.</p> 
<p>For each element there are a number of attributes that can be set (e.g. the name of the file to load, the number of 
milliseconds to show each frame for). Not every graphic/animation/animationitem has to contain every element. If none are set
then the missing attributes take their value from it's parent. 'animationitems' take defaults from 'animation', 'animation' and 
'graphic' take from 'global', and 'global' uses hard-coded defaults. For example the attribute 'bmp_type' determines whether
you want to load the bitmap as a memory, system or video bitmap. If it isn't set in an 'animationitem' the value is taken 
from 'animation', if 'animation' does not contain the attribute then 'global' is checked, and if 'global' does not contain anything 
then the default is used (which happens to be memory bitmap).</p> 
<p>animationitems-&gt;animation-&gt;global-&gt;hard coded.</p>
<p>graphic-&gt;global-&gt;hard coded.</p>
<p>Not all attributes are valid for all elements, for example the attribute 'bmp_file' is the name of the bitmap file to load. 
It makes no sense for it to appear in either the 'global' or 'animation' element, but it can appear in 'graphic' or 'aninationitem' 
elements. Also some values are mandatory and omission will result in an error (e.g. bmp_file is one such mandatory item.</p> 
		<a name="elements"></a>
<h2>Elements and Attributes</h2>
<p>Full details appear below for all attributes, however a short and concise version is contained in the animation.xml file
that is in the tests\animation directory. It's probably best to open up the 
animations.xml file and map the table below to what you see:</p>

<table style="width: 800px">
<tr><th>Attribute</th><th>global</th><th>graphic</th><th>animation</th><th>animationitem</th><th>default</th><th>details</th></tr>
<tr><td>id</td><td></td><td>Y</td><td>Y</td><td></td><td>the filename</td>		<td>The name of the animation. Must be unique</td>
</tr>
<tr><td>bmp_file</td><td></td><td>Y</td><td></td><td>Y</td><td>error if omitted</td>		<td>The name of the bmp file/master bitmap file referenced</td>
</tr>
<tr><td>bmp_type</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>1 (memory)</td>		<td>How bitmap is created 1 for memory, 2 for system and 3 for video</td>
</tr>
<tr><td>depth</td><td>Y</td><td>Y</td><td>Y</td><td></td><td>32</td>		<td>Colour depth of image. 8,15,16,24,32</td>
</tr>
<tr><td>ppmask</td><td>Y</td><td>Y</td><td>Y</td><td></td><td>0</td>		<td>Setting to 1 will 
create a PPCOL mask for the graphic.</td>
</tr>
<tr><td>millisecondwait</td><td>Y</td><td></td><td>Y</td><td>Y</td><td>0    </td>		<td>The time in milliseconds to show this or 0 for no pause</td>
</tr>
<tr><td>framewait</td><td>Y</td><td></td><td>Y</td><td>Y</td><td>0   </td>		<td>Similar to millisecondwait but in frames</td>
</tr>
<tr><td>loop</td><td>Y</td><td></td><td>Y</td><td></td><td>once</td>		<td>Dictates what happens after 
the last animation frame has been shown:<br />
once : animation stops after the last one<br />
start : animation repeats from start <br />
reverserepeat : animation reverses direction<br />
reverseonce : reverses to start then stops<br />
reverseback : reverses to start, goes forward then stops</td>
</tr>
<tr><td>automode</td><td>Y</td><td></td><td>Y</td><td></td><td>1</td>		<td>If set to off (0) then 
the animation will only change when you tell it.<br />
Default: 1</td>
</tr>
</table><br /><strong>
Sheet/Tiled Image attributes</strong><table style="width: 800px">

<tr><th>Attribute</th><th>global</th><th>graphic</th><th>animation</th><th>animationitem</th><th>default</th><th>details</th></tr>
<tr><td>isasheetgraphic</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>0</td>		<td>This graphic is a sheet (tiled) item, i.e. it is a sub-section of a larger graphic.</td>
</tr>
<tr><td>sheetgrid</td><td>Y</td><td></td><td>Y</td><td></td><td>0</td>		<td>Sheet items have a 1 pixel border</td>
</tr>
<tr><td>sheetitemwidth</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>64</td>		<td>The width/height in pixels of the graphic.</td>
</tr>
<tr><td>sheetitemheight</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>64</td>		<td>The width/height in pixels of the graphic.</td>
</tr>
<tr><td>originx</td><td></td><td>Y</td><td>Y</td><td>Y</td><td>0</td>		<td>The location within the bitmap where this animation/graphic starts.</td>
</tr>
<tr><td>originy</td><td></td><td>Y</td><td>Y</td><td>Y</td><td>0</td>		<td>The location within the bitmap where this animation/graphic starts.</td>
</tr>
<tr><td>tilex</td><td></td><td>Y</td><td></td><td>Y</td><td>-1</td>		<td>-1 to use absolute pixel postions (originx/originy)<br />
0 or more the grid location (multiples of sheetitemwidth/height) within the master bitmap</td>
</tr>
<tr><td>tiley</td><td></td><td>Y</td><td></td><td>Y</td><td>-1</td><td>As tilex for the y co-ordinate</td></tr>
<tr><td>sequencecount</td><td></td><td></td><td>Y</td><td></td><td>0</td><td>
If the graphics in the animation simply go from tilex=0 for a number of sequential tiles then instead of
using the animationitem elements, simply set this value to the number of animationitems and the 
system will do the rest (0 means not being used, with a maximum of 100 - to avoid daft errors). It will not read any animation item elements. For example if you set this to be 4, 
then from originx/originy it will get tiles for tilex=0,1,2,3 all with size sheetitemwidth/height. This attribute overrides isasheetgraphic, tilex and tiley.</td></tr>
</table>
<br />
<a name="methods"></a><h2>Methods</h2>
There are two main classes to use, AnimationLibrary and Animation. AnimationLibrary manages the bitmaps and the XML and is used mainly to initialise and load the graphics described in the XML file. The main class used is the Animation 
class that controls the loaded graphics and animations.<br /> The class 'Animation' actually refers to animations and static graphics. A static graphic is stored internally as a single frame animation, i.e. for 
static graphics you would create an animation object as normal and can make use of all the functions, like the timers, fade, etc. 
If you don't need all the bloat associated with an animation object and just wish to retrieve the BITMAP and that is all, see the section 
below entitled 'Static Graphics'.<br />

<h2>AnimationLibrary class</h2>
<table style="width:800px">
<tr><th>Method/Data</th><th>Details</th></tr>
<tr><td>AnimationLibrary(string file, int fps, BitmapType maxbmp,(*bitmapcreator)(string))</td><td>Constructor. See Usage section below for full details. 
This constructor initialises the Animation library/repository, loads up all the graphics and creates the animations. 
file is the XML file or string of XML data to load. 
FPS is the FPS the Animation system should expect (for timing the animations correctly). 
maxbmp is the 'best' graphic type to use (memory, system, video). This effectively will override what is set in the XML as the bitmap type to use (see also the 'capbmptype' attribute of the Configurator module).
bitmapcreator is a function pointer. By default all graphics references by the XML attribute 'bmp_file' are initially loaded using load_bmp. If you wish to have the system do something else (e.g. apply pre-rendering, load a file in a different system/format), use this. See 'Custom bitmap loader' section below.
Defaults to 'animations.xml', 60FPS, video memory is the maximum (i.e. no maximum) and NULL (no function pointer). To avoid the graphics being loaded, simply pass in "" as the XML and ignore the error, then call LoadAnimations()</td></tr>
<tr><td>LoadError</td><td>Set to true if an error occurred during the constructor or loading of animations. Useful if the configuration class is not being used (therefore no access to the GlobalErrorString)</td></tr>
<tr><td>GetAnimation(string)</td><td>Retrieve an animation. See code examples for why you would need this rather than using an Animation object</td></tr>
<tr><td>GetFirstGraphic(string)</td><td>returns a BITMAP (or null) of the first (or usually only) item in the repository called 'string'. See 'static graphics' section below</td></tr>
<tr><td>DestroyAll()</td><td>remove everything and clean up. Normally you DO NOT call this as deleting the AnimationLibrary object you create automatically calls this</td></tr>
<tr><td>LogEntry()</td><td>lets you write stuff to a log file. See code for examples. this is a static</td></tr>
<tr><td>DebugData()</td><td>dump the entire repository structure to a file. done automatically</td></tr>
<tr><td>fps</td><td>the fps the system is using. only modify if not set via the xml or constructors for some reason. Note, if the AXL Framework is being used then it's FPS will override this value if different. This is because the AXL Framework runs a game timer loop set by it's FPS.</td></tr>
<tr><td>SetGlobalErrorString()</td><td>set the current error for use somewhere or other</td></tr>
<tr><td>GetGlobalErrorString()</td><td>get the current error for use somewhere or other</td></tr>
<tr><td>StoredBitmaps</td><td>map&lt;string, BITMAP*&gt; of all the graphics used in the system (but not subbitmaps)</td></tr>
<tr><td>LoadAnimations()</td><td>load and populate the repository from an XML file. This is not normally required as the constructor above automatically calls this method. see next section</td></tr>
</table>

<br /><h2>Animation class</h2>
<table style="width:800px">
<tr><th>Method/Data</th><th>Details</th></tr>
<tr><td>Animation(AnimationLibrary* l, string name)<br />Animation(AnimationLibrary* l, AnimationLibraryFrames* f)</td>
<td>Create an animation object. Get it via a name or a pre-initialised object (see next section).
</td></tr>
<tr><td>NextMove()</td><td>	This performs all the calculations for the animation and should be called every frame.</td></tr>
<tr><td>Pause()</td><td>	Stops the current animation, freezing the time and image</td></tr>
<tr><td>Resume()</td><td>	Continues from a Pause() call</td></tr>
<tr><td>Reset()</td><td>	This will reset the animation to the beginning and all values to the defaults set in the 
animation library</td></tr>
<tr><td>FadeOut(int milliseconds, bool alterbmp=true, int colour=0, int startinglevel=-1)</td><td>Fades the sprite to 'colour' (black if omitted) 
in 'milliseconds' in 256 steps. 'startinglevel' (255 invisible to 0 solid) starts it from another value (-1 from where it last finished). 
<span style="display:none">Will make use of FBlend if included for faster fading (see below). </span>If you wish to fade the sprite to transparent rather than a 
colour, set 'alterbmp' to false and fade will only update it's current level in the range 0-255 and not modify the bitmap.</td></tr>
<tr><td>FadeIn(int milliseconds, bool alterbmp=true, int colour=0, int startinglevel=-1)</td><td>Opposite of FadeOut, going from 0 to 255</td></tr>
<tr><td>ReadOnly_CurrentItem</td><td>Variable.	The BITMAP pointer to the current graphic. You usually grab this after creating an animation, after calling NextMove or Fade step.</td></tr>
<tr><td>GetAutoMode()</td><td>	Whether automode has been set. True means you should simply call NextMove() to progress the animation. 
False means it is being manually stepped and ManualTimerUpdate() should be called every frame instead and NextMove() should be called when the 
next frame should be shown.</td></tr>
<tr><td>ManualTimerUpdate()</td><td>When using single stepping you still need the timers (Fade/countdown - see below) to function correctly.
Call this function everyframe if in manual step mode. See code examples below for more details.
</td></tr>
<tr><td>SetNewAnimation
(string id)</td><td>Changes the current animation to a new one and resets all attributes to their innitial state. See usage below.</td></tr>
<tr><td>SetNewAnimation
(AnimationLibraryFrames*)</td><td>	This is the same as the string variant above but takes in a raw animation pointer (kind of equivalent to the animation object but for the library). This is useful for when speed is of the essence as no lookups are required - the string version has to search it's list of animations to find the correct one. You would usually call this before the game starts:
<p class="code">AnimationLibraryFrames* Ptr;
Ptr=GameLibrary-&gt;GetAnimation("ship1");</p>

Returns NULL on failure.</td></tr>
<tr><td>GetStandardDimensions
(int* w, int* h);</td><td>	Sets the two passed parameters to the size of the BITMAP (passes back the size of the first image only, i.e. assumes all images in the animation are the same size). Use this to avoid using the BITMAP object.</td></tr>
<tr><td>CheckCollision
(int this_x, int this_y, PPCOL_MASK mask, int mask_x, int mask_y);</td><td>
Pixel Perfect Collision detection. This function may be best in your sprite class or abstracted by it, but it is here to show how to do pixel perfect collision. The first two parameters
are the x/y co-ordinates of this animation object (i.e. you supply them because they are not stored with the animation, hence
why it may be best to move this to your sprite class), mask is the PPCOL_MASK of the other bitmap and the mask_x, mask_y are the
co-ordinates of the other bitmap. You do not supply this animations mask because it is already known. Returns true for collision, false for not.
example use: <br />myAnimation->CheckCollision(x,y, otherAnimation->ReadOnly_CurentPPCOLMask, otherx, othery);
<br />Returns 0 if no collision, 1 if bounding box collision only, 2 if pixel perfect collision, -1 if either animation has no PPCOL mask set up.</td></tr>
<tr><td>check_bb_collision_general(x1, y1,w1,h1, x2,y2, w2,h2)<br />
check_bb_collision(mask1, mask2, x1,y1, x2,y2)</td><td>
If bounding box collision detection is all you need, then these two macros will do the job for you. 
The first takes in co-ordinates and width/height of two rectangles and returns 0 or 1 for no collision or collision. 
The second takes two PPCOL_MASK structures instead (it then gets the width/height from these).
</td></tr>

</table>
<h2>Timers and Flags</h2>
<table style="width: 800px">
<tr><th>Method/Data</th><th>	Details</th></tr>
<tr><td>SetCustomCountDown(int timer, int milliseconds)</td><td>Start a custom countdown timer. Useful for things like keeping a logo on screen, delaying the start of a sprite, setting a time for an animation to end, etc. You are allowed four timers (1,2,3,4). The parameter 'timer' is one of these values and 'milliseconds' is the time taken. When the timer has reached zero a flag is set. Refer to the flags below for more details.<br /><br />NOTE: the current system is set up to 4, but is actually defined by a constant (MAX_COUNTDOWN_TIMERS) that can be changed to any value.</td></tr>
<tr><td>ReadOnly_EndReached</td><td>	This is set to true when the animation has finished. Obviously this is only set for non-repeating animations. It is just a flag and can be ignored if nothing special is to happen when an animation finishes (animations ended will simply show the last image).</td></tr>
<tr><td>ReadOnly_Timers[x]</td><td>	x Represents 0,1,2,3,4 being the fade timer (0 element) and the four custom timers available to be set with SetCustomCountDown(). When no timer/fade has been set/started the value will be true, when a timer/fade is in progress the value will be false, when the timer/fade has finished the value will be true. i.e. finished is the same as not started.</td></tr>
<tr><td>ReadOnly_TimersCounter[x]</td><td>Returns the current value of the countdown/fade timer. 
Use the fade timer in conjunction with FadeIn/Out() to pass the value to you own custom fader (e.g. transparent.)</td></tr>
</table>

<h2>Less Commonly Used Functions/Data</h2>
<table style="width: 800px">
<tr><th>Method/Data</th><th>	Details</th></tr>
<tr><td>SetNewSpeedMS(int)

SetNewSpeedFramecount(int)</td><td>	Will change the animation rate in milliseconds or frames for all frames in this animation.</td></tr>
<tr><td>SetNewLoopType
(LoopType)</td><td>	Change the way the animation loops. LoopType can be one of 
LOOP_START, 
LOOP_REVERSEREPEAT, LOOP_REVERSEONCE, LOOP_REVERSEBACK, 
LOOP_ONCE</td></tr>
<tr><td>GetCurrentSpeedMS()
GetCurrentSpeedFrameCount()</td><td>Returns the current animation speed in milliseconds or frames
</td></tr>
<tr><td>BitmapType  ReadOnly_TypeOfBitmap</td><td>Returns the type of the bitmap, TYPE_VIDEO, TYPE_SYSTEM, TYPE_MEMORY</td></tr>
<tr><td>PPCOL_MASK*  ReadOnly_CurentPPCOLMask</td><td>
For the current bitmap this returns the PPCOL mask for it (if set up to be used in the XML/library). Use the supplied functions
(below) or download the whole PPCOL library for implementing pixel perfect collision detection.</td></tr>
</table>
<a name="optimum"></a>
<h1>Optimisations and Setup</h1>
<p>The class mainly used in games in real time will be the Animation class. Within this the method most called and available 
for optimisation is the NextMove() as it is called every frame and contains the main animation logic. To speed up this 
functions set up the following definitions at the top of the axl.h header file</p>
<ul>
    <li>If you are using FBlend, set USE_FBLEND to 1. Remember to include the library file (.a/.lib), and on testing this function is no faster than Allegro due to the coding put in to work with any mask colour</li>
    <li>If you are not using fades, set OPTIMISE_NOFADE to 1</li>
    <li>If you are not using any countdown timers, set OPTIMISE_NOCOUNTERS to 1</li>
    <li>If you are using countdown timers but not the default of 5, change the MAX_COUNTDOWN_TIMERS</li>
</ul>

<a name="playback"></a>
<h1>Usage</h1>
<a name="init"></a><h2>Initialising and Loading</h2>
In your source code you need to include the main header file and use the AXL namespace:
<p class="code">#include "axl_animations.h";
using namespace AXL_Projects;</p>

To start using an animation you need to create an animation library object (one global or static scope 
item should be enough):</p>
<p class="code">AnimationLibrary* GameLibrary;
GameLibrary=new AnimationLibrary();</p>
<p>AnimationLibrary actually takes a number of parameters but all have defaults as the defaults take all the values from the XML
file. Note, The playback library does not use timers, it relies on your code 
calling an update function every frame and uses this in conjunction with the FPS parameter to determine when the next frame is to 
be shown:</p>
<p><b>AnimationLibrary(string XMLfile, int fps, BitMapType maxbmp)</b></p>
<p>The defaults are the animation file to load being 'animations.xml', fps=60 and the maximum type of graphic being TYPE_VIDEO (i.e. no maximum as Video is the highest, other choices are TYPE_SYSTEM and TYPE_MEMORY)</p>
<p>During the constructor, the XML file is loaded which creates the library of animation items and sets all the defaults mentioned in the full
constructor above. Adding resources to the library in code instead of XML is mentioned later. To check if the animations loaded ok check the LoadError data member:</p>
<p class="code">if(!GameLibrary-&gt;LoadError)
	abort();</p>

The parameter 'XMLfile' does not have to be a filename, it can be the actual XML data as well. See example1 in the animation test directory.
<br />At any time, new animations can be loaded (old ones automatically destroyed) by using the method 'LoadAnimations':
<p class="code">if(!GameLibrary-&gt;LoadAnimations())
	abort();</p>
<p>LoadAnimations() takes two parameters, that can both be defaulted (as in the code above):</p>
<p><b>LoadAnimations(string file="animations.xml", bool wipelog=false);</b></p>
<p>The first is the filename of the data file to load and defaults to animations.xml
This can also be actual XML data. The second is to wipe the log file (if used) on loading the XML file. On loading of a library, a log file is produced.</p>
<p>Whenever LoadAnimations() is called any previously loaded bitmaps for the object will be deleted and all memory freed.</p>
<p><strong>NOTE:</strong> You must have Allegro initialised first so it can create and open bitmaps and do any converstion of the colour depth correctly. 
</p>
If you wisht to initialise the AnimationLibrary but not load/set the animations for some reason then pass in "" to the constructor, ignore the LoadError flag then call LoadAnimations()
<a name="seq"></a><h2>Running Animations</h2>

<p>Once the library is set up, you need to create animation items for playback. The samples do not use any sprite 
library, they simply create one animation object and draw it. Normally you would have one animation object per sprite:</p>
<p class="code">Animation* myAnimation;
myAnimation=new Animation(GameLibrary,"fuel");</p>

<p>The first parameter is the AnimationLibrary object previously created. The second parameter assigns its animation, 
this is the name given to the animation and is referenced by the ID attribute in the XML file (or the name string you 
give it if not using XML).</p>
<p>Within your game logic (called every frame) you tell the animation object to update its state:</p>

<p class="code">if(key[KEY_SPACE]) CanMove=true;
if(GetAutoMode) myAnimation-&gt;NextMove();
else
{
 if(CanMove) TempAnimation->NextMove();
 else TempAnimation->ManualTimerUpdate();
}</p>


<p>If in auto mode then a call to NextMove is all that is required. When in maual mode we need to only update the frames
when told to but still keep to keep the timers/fade running. So we call NextMove if the SPACE key is pressed or if not
we just update the timers (NextMove will call the timer updates itself).</p>
<p>In your drawing code you simply reference the public data variable 'ReadOnly_CurrentItem' to get a BITMAP pointer 
to the current frame, e.g.</p>
<p class="code">draw_sprite(buffer, myAnimation-&gt;ReadOnly_CurrentItem, 100,180);</p>

<p>The current frame is set by the call to NextMove().</p>
If you need to change animations then use <span class="code">myAnimation-&gt;SetNewAnimation("item_id");</span> to
change the animation and reset all values to the animation 'item_id' stored in the XML. Obviously this requires a
string lookup, so if speed is critical then you can do:<p class="code">AnimationLibraryFrames* newAnimation;
newAnimation=GameLibrary->GetAnimation("item_id");
myAnimation-&gt;SetNewAnimation(newAnimation);
</p>
That is about it really for simply showing and animation.</p>

<h2>Static Graphics</h2>
If all you want is to retrieve a static graphic and have no need for any of the animation helper methods/data, then you can
access the BITMAP directly without the overhead of creating a new object:
<p class="code">
	BITMAP* logo=GameLibrary->GetFirstGraphic("logo");
</p>
This assumes you have already instantiated an AnimationLibrary object and called it GameLibrary.
<h2>Graphics Mode Change</h2>
If you change graphics modes (e.g. set_gfx_mode() ), for example from a menu option to allow the user to change resolution, etc, then you should delete all animations and reload. This can be done by simply calling 'delete anim' where anim is your animation library, and re-initialising it. If you are using the Framework, it will try to do it for you if you call the Framework method RestartSystem(). This is because if video or system bitmaps are being used they will/might become invalid and/or corrupted. Memory bitmaps should be ok though any change to colour depth/conversion may affect them.
<h2>Custom Bitmap Loader</h2>
When graphics are initially loaded they are created using the load_bmp function. After this they are transformed into the correct format (e.g. 
video, system, memory). If you wish to use another file format, e.g. png, or maybe retrieve the graphic from a different location (e.g. a dat file, a custom file system), 
or if you wish to apply some kind of transformation (e.g. rotation, lighting, etc) then you can pass in the name of a function you write to the Animation Library constructor.
This will receive a std::string as the entry name (which is the XML attribute 'bmp_file') and should return a BITMAP* on exit. Or if it fails, passing back NULL will let the system know 
that an error occurred. Animation example 4 shows an example of this pointer, but assuming you called the constructor like this:
<p class="code">AnimationLibrary* al=new AnimationLibrary("animations.xml", 60, TYPE_VIDEO, MyBitmapCallback);</p>
And in your code you created MyBitmapCallback as:
<p class="code">BITMAP* MyBitmapCallback(const std::string& filename)
{
	BITMAP* tmp=load_bmp(filename.c_str(),NULL);
	if(tmp)
	{
		BITMAP* newtmp=create_bitmap(tmp->w,tmp->h);
		clear_to_color(newtmp,makecol(255,0,255));
		draw_sprite_v_flip(newtmp,tmp,0,0);
		destroy_bitmap(tmp);
		return newtmp;
	}
	else 
		return NULL;
}
</p>
It will simply pass back a flipped version. You could easily change this to interrogate the string name and appy different things, e.g. simply return back 
a bitmap created using load_bmp for most, but for those ending in ROTATExxx (where xxx is a number), you could rotate the bitmap by xxx degrees. You could then simply pass in
the same bitmap for each graphic item and let the code do the work.<br /><br />
NOTE: the callback will only be called for graphics that are actually loaded. i.e. it will not be called for subbitmaps (those with the 'issheetgraphic' set to 1) or those that are 
duplicates (have the same bmp_file entry). Also note, that you should ALWAYS return back a memory bitmap as the transformation to the correct type will be made by the system.
<a name="tutorial"></a>
<h1>Examples</h1>
These are found in the tests\animation directory (.\example1 and .\example2). VS2005 and Dev-C++ projects have already been created. If not using either of these two IDe's then follow the installation section, i.e. include tinyXML library file (or tinyXML source files), the main.cpp in the example directory and axl_animation.cpp. Additionally, example 2 requires axl_config.cpp, and example three requires axl_config.cpp and axl_framework.cpp
<ul><li>The first example (example 1) uses the Animation module to load up some graphics and Animations. It shows a few different ways of retrieving graphics and animations. It uses standard Allegro code to setup and run the program. The program uses the animations.xml file for the graphics/animations. There are two additional files (animations_tiledgrid.xml, animations_single.xml). These contain exactly the same graphics and the example will run exactly the same. The difference is that the default animations.xml file stores all the graphics in a single bitmap, animations_tiledgrid.xml stores all the graphics in a single bitmap but each animation has the tiles separated by a border, the animations_single.xml stores each graphic and animation frame in a separate file. To try each one out, rename them so that the one you want is called animations.xml</li>
<li>The second example (example 2) is the same as example 1 but instead of using code to set up allegro the configuration module is used. This has many advantages, including less code, the ability to change Allegro startup values via a XML file and to change how Allegro starts. Try this example out after you have read the Configuration help and examples</li>
<li>The third example (example 3) is the same as the previous examples except instead of writing letting the configuration simply start allegro and we code our buffers and timer loop, the Framework does it all for us. As you can see in the code, minimal Allegro set up is required. In addition to this change a couple of extra menu options are provided to show the Framework features (e.g. resetting graphics system and reloading data). Try out this example only after you have fully read and understood the previous animation examples, the Configurator help and examples, and the Framework help and examples.</li>
<li>The fourth (example 4) is the same as example 3 except it uses a callback in the constructor to flip the animations</li>
</ul>
<h2>XML as data</h2>
<p>Instead of passing in the name of a XML file to the constructor you can specify XML as a string instead. This is useful if you 
are reading the XML from a source other than a file (e.g. a dat file) or you do not wish the user to modify values. Remember that all attributes 
need to be quoted. The easiest way to do this is to simply copy the XML data from the sample animations.xml files. For example:</p>
<p class="code">
std::string anim="&lt;?xml version=\"1.0\" encoding=\"UTF-8\"?&gt;"
"&lt;animations&gt;"
"	&lt;global "
"		depth=\"32\""
"		bmp_type=\"1\""
"	/&gt;"
"	&lt;graphic "
"		id=\"master\" "
"		bmp_file=\"sheet.bmp\" "
"		isasheetgraphic=\"0\" "
"	/&gt;"
"	&lt;animation id=\"fuel\" "
"		bmp_file=\"sheet.bmp\"		"
"		originx=\"0\" originy=\"32\" "
"		sheetitemwidth=\"24\" sheetitemheight=\"24\" "
"		isasheetgraphic=\"1\" "
"		sequencecount=\"4\""
"	/&gt;"
"&lt;/animations&gt;";
MyAnimLibrary=new AnimationLibrary(anim);</p>


<a name="manlibrary"></a>
<h1>Manual Library</h1>

<p>This section deals with writing code to create an animation library rather than using an XML file. It can be safely skipped. Only public data/methods will be described.</p>

The <b>AnimationLibrary</b> object has one or more <b>AnimationLibraryFrames</b> objects <br />
<b>AnimationLibraryFrames</b> has one or more <b>AnimationLibraryFrame</b> objects

<h1><i>AnimationLibrary</i></h1>
<p>This represents your library of animations. It is the object you interact with most when maintaining the library and is what is used in the playback library.</p>

<h2>Commonly Used Methods and Data</h2>
<table>
<tr><th>Method/Data</th><th>	Details</th></tr>
<tr><td>AnimationLibrary()</td><td>	The constructor. Create an animationlibrary first before all else. Refer to the Playback section for details on this method.
The destructor will deleted all stored data (i.e. all AnimationLibraryFrames objects)</td></tr>
<tr><td>AddAnimation (AnimationLibraryFrames* anim)</td><td>	The animation library stores a list of all your animations, use this method to add an animation to the list. Refer to animationlibrary frames for more information.</td></tr>
<tr><td>Bool LoadAnimations (string file="animations.xml", bool wipelog=false)</td><td>	This will load up an XML file detailing the animations rather than having to code AddAnimation() calls. Refer to the playback library above for more details.</td></tr>
<tr><td>int fps</td><td>	The fps set for the library. This is how the library knows when to change frames automatically. This is really for read-only purposes and should be set in the constructor.
</td></tr>
<tr><td>DebugData (char* file="animationslogdebug.log")</td><td>	If you are using the allegro_core library (refer to introduction) then this will output to the log file all the animations in a nice format.</td></tr>
</table>

<h1><i>AnimationLibraryFrames</i></h1>
<p>This represents one unit of animation. It is a series of AnimationLibraryFrame objects, i.e. one AnimationLibraryFrame represents one bitmap/animation frame. AnimationLibraryFrames describes how the animation is synchronised, looped and controlled. This can be equated to the Animation object in the playback library as it represents the same unit of work (a series of frames).</p>

<h2>Commonly Used Methods and Data</h2>

<table>
<tr><th>Method/Data</th><th>	Details</th></tr>
<tr><td>AnimationLibraryFrames(string id)<br /><br />

AnimationLibraryFrames(<br />string id, LoopType lt=LOOP_INVALID,<br />int msWait=-1, int fWait=-1,<br />bool autom=true);</td><td>	The constructor. Id is how you refer to an animation in code (each animation series is stored in a hash table). Normally the first constructor will do. The parameters are:
<ul><li>LoopType: how the animation loops at the end</li>
<li>msWait/fWait: default waiting time between frames in milliseconds (ms) or number of frames. MS takes precendence. Default is to use what is set in the AnimationLibrary object.</li>
<li>Autom: true to automatic mode (animation is shown as described by the wait/looptype and other methods), manual is single stepping.</li>

Refer to the playback library for further details on these parameters.</li>

</ul>
The destructor will deleted all stored data (i.e. all AnimationLibraryFrame objects)</td></tr>
<tr><td>AddAnimationFrame (AnimationLibraryFrame* ai);</td><td>	The animationlibraryframes stores a list of all your animation items in a list, use this method to add an animation item to the list. Refer to animationlibrary frame object for more information.</td></tr>
<tr><td>String Id</td><td>The ID of the animation. This is really for read-only purposes and should be set in the constructor.</td></tr>
</table>


<h1><i>AnimationLibraryFrame</i></h1><p>This represents a single animation frame. A bitmap if you like, but with additional data.</p>

<h2>Commonly Used Methods and Data</h2>

<table>
<tr><th>Method/Data</th><th>	Details</th></tr>
<tr><td>AnimationLibraryFrame (string file="", int msWait=-1, int fWait=-1);</td><td>	The constructor. Default is to use what is set in the AnimationLibrary object. The first parameter is the name of the bitmap file (in a sub-directory called gfx.<br />

A file will be added to the library once only. This means that loading will occur once and no memory will be wasted with multiple versions of the same file.<br />

The destructor will delete all stored data (i.e. loaded bitmaps)
</td></tr>
</table>

<h1><i>Summary
</i></h1><p>As you can see, you create a AnimationLibrary for both playback, manual creation of a library and automated creation of a library via an XML file.</p>

<p>A library is created as follows:</p>
<ol><li>Create a single AnimationLibrary object for your library</li>
<li>Create an AnimationLibraryFrames object for each animation sequence</li>
<li>For each item in the animation create a AnimationLibraryFrame object and add it to the AnimationLibraryFrames object via the AddAnimationFrame method.</li>
<li>When you delete an AnimationLibrary object all AnimationLibraryFrames objects are deleted and memory reclaimed. When an AnimationLibraryFrames object is deleted all the AnimationLibraryFrame objects and bitmaps are deleted and memory reclaimed.</li>
</ol>

</div>
</body>
</html>